/*______________________________________________________________________________
 *
 * Copyright 2005 NORSYS
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * (1) Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 *
 * (2) Redistributions in binary form must reproduce the above copyright
 *     notice, this list of conditions and the following disclaimer in
 *     the documentation and/or other materials provided with the
 *     distribution.
 *
 * (3) The name of the author may not be used to endorse or promote
 *     products derived from this software without specific prior
 *     written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 * OF THE POSSIBILITY OF SUCH DAMAGE.
 *______________________________________________________________________________
 *
 * Created on 27 sept. 2005
 * Author: Arnaud Bailly
 */
package speculoos.manager;

import speculoos.core.Mapper;
import speculoos.core.MapperException;
import speculoos.spi.Source;

/**
 * Configuration interface for business mapper components. This interface allows
 * runtime configuration of a manager.
 * 
 * @author nono
 * @version $Id: Configure.java 259 2006-05-23 10:34:50Z /C=FR/ST=Nord/L=Lille/O=Norsys SA/OU=UE/CN=Arnaud Bailly/emailAddress=abailly@norsys.fr $
 */
public interface Configure {

    /**
     * Adds a new configured mapper to this configurable object (manager).
     * 
     * @param name
     *            the name of the mapper. The name uniquely identifies the
     *            mapper within this manager context. Must not be null, nor empty string.
     * @param mapper
     *            a Mapper object. May not be null.
     * @see Mapper
     * @throws MapperConfigurationException
     *             if name is already in use.
     */
    public void addMapper(String name, Mapper mapper)
            throws MapperConfigurationException;

    /**
     * Adds a new configured source to this manager.
     * 
     * @param name
     *            name of the source. Must be unique for all sources in this
     *            context. Must not be null. Must not be the empty string.
     * @param source
     *            the source object. May not be null.
     * @throws MapperConfigurationException
     *             if name is already in use.
     */
    public void addSource(String name, Source source)
            throws MapperConfigurationException;

    /**
     * Associate a mapper and a source by their name in this context. A mapper
     * may be associated with only one source, but a source may be associated
     * with several mappers.
     * 
     * @param mapName
     *            the name of mapper
     * @param srcName
     *            the name of the source
     * @throws MapperConfigurationException
     *             if either <code>mapName</code> or <code>srcName</code>
     *             are not defined in this context.
     */
    public void link(String mapName, String srcName)
            throws MapperConfigurationException;

    /**
     * Adds a new parameter to this context. The <code>value</code> parameter
     * to this method is the default value of the parameter in this context.
     * Default may be overriden with {@link #set(String, Object)}or within the
     * context of a single mapper {@link Mapper}. Default value may be restored
     * with a call to {@link #unset(String)}.
     * 
     * @param param
     *            name of parameter. Must be unique within the context of this
     *            manager, must not be null, must not be empty
     * @param value
     *            default value of the parameter. May not be null.
     * @throws MapperConfigurationException
     *             if <code>param</code> is already registered in this
     *             context.
     */
    public void addParameter(String param, Object value)
            throws MapperConfigurationException;

    /**
     * Sets the value of given parameter in this context. The parameter
     * <code>name</code> must have been registered in this context with method
     * {@link #addParameter(String,Object)}before. Default value may be
     * restored with a call to {@link #unset(String)}.
     * 
     * @param param
     *            name of parameter.
     * @param value
     *            the new value of the parameter.
     * @return the old value of the parameter.
     * @throws MapperConfigurationException
     *             if <code>param</code> does not name a parameter in this
     *             context or if invoked after configuration has been closed with
     *             setConfigured().
     */
    public Object set(String param, Object value)
            throws MapperConfigurationException;

    /**
     * Unset the value of this parameter whose value is restored to the default
     * (as defined by call to method {@link #addParameter(String,Object)}.
     * 
     * @param param
     *            name of parameter to restore.
     * @return the old value of parameter. This may be the default if no value
     *         has been set yet.
     * @throws MapperConfigurationException
     *             if <code>param</code> does not name a parameter in this
     *             context.
     */
    public Object unset(String param) throws MapperConfigurationException;

    /**
     * Resest this context to clean state. This means that no object is
     * registered and all resources are freed. This method may only be called if
     * the underlying manager object is not in <em>ready</em> state.
     * 
     * @see Manage
     * @throws MapperConfigurationException
     *             if this object is not in a state that allows resetting.
     */
    public void reset() throws MapperConfigurationException;

    /**
     * Ends the configuration process of this manager. It is now ready to be
     * started and to operate. No call to any other method in this interface
     * than {@link #reset()}or any <em>query</em> method is allowed.
     * 
     * @throws MapperConfigurationException
     *             if called at wrong time in this manager life-cycle.
     */
    public void setConfigured() throws MapperConfigurationException;

    /**
     * Retrieve the current value of a parameter in this configure instance.
     * 
     * @param string
     *            name of parameter
     * @return current value of parameter
     */
    Object lookup(String string) throws MapperException;

}